﻿using System;
using System.Globalization;

namespace RoughHtml.w3c
{
    public abstract class Parser
    {

        /**
         * Allow an application to request a locale for errors and warnings.
         *
         * <p>CSS parsers are not required to provide localisation for errors
         * and warnings; if they cannot support the requested locale,
         * however, they must throw a CSS exception.  Applications may
         * not request a locale change in the middle of a parse.</p>
         *
         * @param locale A Java Locale object.
         * @exception CSSException Throws an exception
         *            (using the previous or default locale) if the 
         *            requested locale is not supported.
         * @see CSSException
         * @see CSSParseException
         */
        public abstract void setLocale(CultureInfo locale);

        /**
         * Allow an application to register a document event handler.
         *
         * <p>If the application does not register a document handler, all
         * document events reported by the CSS parser will be silently
         * ignored (this is the default behaviour implemented by
         * HandlerBase).</p>
         *
         * <p>Applications may register a new or different handler in the
         * middle of a parse, and the CSS parser must begin using the new
         * handler immediately.</p>
         *
         * @param handler The document handler.
         * @see DocumentHandler
         */
        public abstract void setDocumentHandler(DocumentHandler handler);

        public abstract void setSelectorFactory(SelectorFactory selectorFactory);
        public abstract void setConditionFactory(ConditionFactory conditionFactory);

        /**
         * Allow an application to register an error event handler.
         *
         * <p>If the application does not register an error event handler,
         * all error events reported by the CSS parser will be silently
         * ignored, except for fatalError, which will throw a CSSException
         * (this is the default behaviour implemented by HandlerBase).</p>
         *
         * <p>Applications may register a new or different handler in the
         * middle of a parse, and the CSS parser must begin using the new
         * handler immediately.</p>
         *
         * @param handler The error handler.
         * @see ErrorHandler
         * @see CSSException
         */
        public abstract void setErrorHandler(ErrorHandler handler);

        /**
         * Parse a CSS document.
         *
         * <p>The application can use this method to instruct the CSS parser
         * to begin parsing an CSS document from any valid input
         * source (a character stream, a byte stream, or a URI).</p>
         *
         * <p>Applications may not invoke this method while a parse is in
         * progress (they should create a new Parser instead for each
         * additional CSS document).  Once a parse is complete, an
         * application may reuse the same Parser object, possibly with a
         * different input source.</p>
         *
         * @param source The input source for the top-level of the
         *        CSS document.
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         * @see InputSource
         * @see #parseStyleSheet(java.lang.String)
         * @see #setDocumentHandler
         * @see #setErrorHandler
         */
        public abstract void parseStyleSheet(InputSource source);


        /**
         * Parse a CSS document from a URI.
         *
         * <p>This method is a shortcut for the common case of reading a document
         * from a URI.  It is the exact equivalent of the following:</p>
         *
         * <pre>
         * parse(new InputSource(uri));
         * </pre>
         *
         * <p>The URI must be fully resolved by the application before it is passed
         * to the parser.</p>
         *
         * @param uri The URI.
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         * @see #parseStyleSheet(InputSource) 
         */
        public abstract void parseStyleSheet(String uri);

        /**
         * Parse a CSS style declaration (without '{' and '}').
         *
         * @param styleValue The declaration.
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         */
        public abstract void parseStyleDeclaration(InputSource source);


        /**
         * Parse a CSS rule.
         *
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         */
        public abstract void parseRule(InputSource source);

        /**
         * Returns a string about which CSS language is supported by this
         * parser. For CSS Level 1, it returns "http://www.w3.org/TR/REC-CSS1", for
         * CSS Level 2, it returns "http://www.w3.org/TR/REC-CSS2". Note that a
         * "CSSx" parser can return lexical unit other than those allowed by CSS
         * Level x but this usage is not recommended.
         */
        public abstract String getParserVersion();

        /**
         * Parse a comma separated list of selectors.
         * 
         * 
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         */
        public abstract SelectorList parseSelectors(InputSource source);


        /**
         * Parse a CSS property value.
         * 
         * 
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         */
        public abstract LexicalUnit parsePropertyValue(InputSource source);


        /**
         * Parse a CSS priority value (e.g. "!important").
         * 
         * 
         * @exception CSSException Any CSS exception, possibly
         *            wrapping another exception.
         * @exception java.io.IOException An IO exception from the parser,
         *            possibly from a byte stream or character stream
         *            supplied by the application.
         */
        public abstract bool parsePriority(InputSource source);
    }
}
